---
title: 快速开始
description: Build your first realtime voice assistant using the OpenAI Agents SDK in minutes.
---

import { Steps, Aside, Code } from '@astrojs/starlight/components';
import helloWorldExample from '../../../../../../../examples/docs/voice-agents/helloWorld.ts?raw';
import createAgentExample from '../../../../../../../examples/docs/voice-agents/createAgent.ts?raw';
import multiAgentsExample from '../../../../../../../examples/docs/voice-agents/multiAgents.ts?raw';
import createSessionExample from '../../../../../../../examples/docs/voice-agents/createSession.ts?raw';
import configureSessionExample from '../../../../../../../examples/docs/voice-agents/configureSession.ts?raw';
import handleAudioExample from '../../../../../../../examples/docs/voice-agents/handleAudio.ts?raw';
import defineToolExample from '../../../../../../../examples/docs/voice-agents/defineTool.ts?raw';
import toolApprovalEventExample from '../../../../../../../examples/docs/voice-agents/toolApprovalEvent.ts?raw';
import guardrailsExample from '../../../../../../../examples/docs/voice-agents/guardrails.ts?raw';
import guardrailSettingsExample from '../../../../../../../examples/docs/voice-agents/guardrailSettings.ts?raw';
import audioInterruptedExample from '../../../../../../../examples/docs/voice-agents/audioInterrupted.ts?raw';
import sessionInterruptExample from '../../../../../../../examples/docs/voice-agents/sessionInterrupt.ts?raw';
import sessionHistoryExample from '../../../../../../../examples/docs/voice-agents/sessionHistory.ts?raw';
import historyUpdatedExample from '../../../../../../../examples/docs/voice-agents/historyUpdated.ts?raw';
import updateHistoryExample from '../../../../../../../examples/docs/voice-agents/updateHistory.ts?raw';
import customWebRTCTransportExample from '../../../../../../../examples/docs/voice-agents/customWebRTCTransport.ts?raw';
import websocketSessionExample from '../../../../../../../examples/docs/voice-agents/websocketSession.ts?raw';
import transportEventsExample from '../../../../../../../examples/docs/voice-agents/transportEvents.ts?raw';
import thinClientExample from '../../../../../../../examples/docs/voice-agents/thinClient.ts?raw';

<Steps>

0. **创建项目**

   在本快速上手中，我们将创建一个可在浏览器中使用的语音智能体。若要从头开始一个新项目，您可以尝试 [`Next.js`](https://nextjs.org/docs/getting-started/installation) 或 [`Vite`](https://vite.dev/guide/installation.html)。

   ```bash
   npm create vite@latest my-project -- --template vanilla-ts
   ```

1. **安装 Agents SDK**

   ```bash
   npm install @openai/agents zod@3
   ```

   或者，您也可以安装 `@openai/agents-realtime`，获取独立的浏览器版本包。

2. **生成客户端临时令牌**

   由于该应用将在用户浏览器中运行，我们需要一种安全的方式通过 Realtime API 连接到模型。为此，可以使用在后端服务器上生成的[临时客户端密钥](https://platform.openai.com/docs/guides/realtime#creating-an-ephemeral-token)。在测试时，您也可以使用 `curl` 和常规的 OpenAI API key 来生成密钥。

   ```bash
   export OPENAI_API_KEY="sk-proj-...(your own key here)"
   curl -X POST https://api.openai.com/v1/realtime/client_secrets \
      -H "Authorization: Bearer $OPENAI_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "session": {
          "type": "realtime",
          "model": "gpt-realtime"
        }
      }'
   ```

   响应的顶层会包含一个以 "ek\_" 前缀开头的 "value" 字符串。稍后您可以使用此临时密钥建立 WebRTC 连接。请注意，该密钥仅在短时间内有效，需要定期重新生成。

3. **创建第一个智能体**

   创建新的 [`RealtimeAgent`](/openai-agents-js/openai/agents-realtime/classes/realtimeagent/) 与创建常规的[`智能体`](/openai-agents-js/zh/guides/agents)非常相似。

   ```typescript
   import { RealtimeAgent } from '@openai/agents/realtime';

   const agent = new RealtimeAgent({
     name: 'Assistant',
     instructions: 'You are a helpful assistant.',
   });
   ```

4. **创建会话**

   与常规智能体不同，语音智能体在一个持续运行并监听的 `RealtimeSession` 中工作，它会随时间处理与模型的对话和连接。该会话还会处理音频处理、打断，以及我们稍后将介绍的许多其他生命周期功能。

   ```typescript
   import { RealtimeSession } from '@openai/agents/realtime';

   const session = new RealtimeSession(agent, {
     model: 'gpt-realtime',
   });
   ```

   `RealtimeSession` 构造函数将 `agent` 作为第一个参数。该智能体将是用户首先能够交互的对象。

5. **连接到会话**

   要连接到会话，您需要传入之前生成的客户端临时令牌。

   ```typescript
   await session.connect({ apiKey: 'ek_...(put your own key here)' });
   ```

   这将在浏览器中通过 WebRTC 连接到 Realtime API，并自动配置麦克风和扬声器用于音频输入与输出。如果您在后端服务器（如 Node.js）上运行 `RealtimeSession`，SDK 将自动使用 WebSocket 作为连接方式。您可以在[传输机制](/openai-agents-js/zh/guides/voice-agents/transport)指南中了解不同的传输层。

6. **整合到一起**

   <Code lang="typescript" code={helloWorldExample} />

7. **启动并开始对话**

   启动您的 Web 服务器并访问包含新 Realtime Agent 代码的页面。您应该会看到麦克风访问请求。授予权限后，即可开始与智能体交谈。

   ```bash
   npm run dev
   ```

</Steps>

## 后续步骤

从这里开始，您可以设计并构建自己的语音智能体。语音智能体包含与常规智能体相同的许多功能，同时也有其独特之处。

- 了解如何为语音智能体添加：
  - [工具](/openai-agents-js/zh/guides/voice-agents/build#tools)
  - [交接](/openai-agents-js/zh/guides/voice-agents/build#handoffs)
  - [护栏](/openai-agents-js/zh/guides/voice-agents/build#guardrails)
  - [处理音频打断](/openai-agents-js/zh/guides/voice-agents/build#audio-interruptions)
  - [管理会话历史](/openai-agents-js/zh/guides/voice-agents/build#session-history)

- 进一步了解不同的传输层。
  - [WebRTC](/openai-agents-js/zh/guides/voice-agents/transport#connecting-over-webrtc)
  - [WebSocket](/openai-agents-js/zh/guides/voice-agents/transport#connecting-over-websocket)
  - [构建自定义传输机制](/openai-agents-js/zh/guides/voice-agents/transport#building-your-own-transport-mechanism)
